~ chicken-core (master) /manual/Module (chicken port)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken port)56This module contains various extended port definitions.78All errors related to failing port operations will signal a condition9of kind {{exn}}.1011* New in CHICKEN 5.4.0: Errors caused by underlying C calls that12 change errno will produce a condition object with an {{errno}}13 property, which can be accessed with14 {{(get-condition-property <the-condition-object> 'exn 'errno)}}.1516=== Port attributes1718==== port-encoding1920<procedure>(port-encoding PORT)</procedure>2122Returns the encoding used for reading and writing data from and to23the given port. Encoding is currently one of the symbols {{utf-8}},24{{latin-1}} or {{binary}}. Note that the encoding can be changed by using25the (SRFI-17) setter procedure for this operation:2627{{(set! (port-encoding PORT) ENCODING)}}2829==== port-name3031<procedure>(port-name [PORT])</procedure>3233Fetch filename from {{PORT}}. This returns the filename that was used to open34this file. Returns a special tag string, enclosed into parentheses for35non-file ports. {{PORT}} defaults to the value of {{(current-input-port)}}.3637Note that the encoding can be changed by using38the (SRFI-17) setter procedure for this operation:3940{{(set! (port-name PORT) STRING)}}414243==== port-position4445<procedure>(port-position [PORT])</procedure>4647Returns the current position of {{PORT}} as two values: row and column number.48If the port does not support such an operation an error is signaled. This49procedure is currently only available for input ports. {{PORT}} defaults to the50value of {{(current-input-port)}}.515253=== Setting the file buffering mode5455==== set-buffering-mode!5657<procedure>(set-buffering-mode! PORT MODE [BUFSIZE])</procedure>5859Sets the buffering-mode for the file associated with {{PORT}} to60{{MODE}}, which should be one of the keywords {{#:full}},61{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it62determines the size of the buffer to be used (if any).6364This procedure doesn't work on custom ports, such as those created with {{make-input-port}} or {{make-output-port}}.6566=== Terminal ports6768==== terminal-name6970<procedure>(terminal-name PORT)</procedure>7172Returns the name of the terminal that is connected to {{PORT}}.7374On Windows, this procedure always raises an exception.7576==== terminal-port?7778<procedure>(terminal-port? PORT)</procedure>7980Returns {{#t}} if {{PORT}} is connected to a terminal and81{{#f}} otherwise.828384==== terminal-size8586<procedure>(terminal-size PORT)</procedure>8788Returns two values, the number of rows and columns of the terminal89that is connected to {{PORT}} or {{0}}, {{0}} if the terminal size can90not be obtained.9192On Windows, this procedure always raises an exception.939495=== Input/output port extensions9697==== with-output-to-port9899<procedure>(with-output-to-port PORT THUNK)</procedure>100101Call procedure {{THUNK}} with the current output-port temporarily102bound to {{PORT}}.103104==== make-input-port105==== make-binary-input-port106107<procedure>(make-input-port READ-CHAR CHAR-READY? CLOSE #!key peek-char read-bytevector read-line)</procedure>108<procedure>(make-binary-input-port READ-U8 U8-READY? CLOSE #!key peek-u8 read-bytevector)</procedure>109110Returns a custom input port. Common operations on this port are111handled by the given parameters, which should be procedures of no112arguments. The following arguments are all different kinds of reader113procedures:114115* {{READ-CHAR}} is the most fundamental reader, and must always be116present. It is a thunk which is called when the next character is117to be read and it should return a character or {{#!eof}}.118* {{READ-U8}} similar to {{READ-CHAR}} but reads and returns a byte.119* {{CHAR-READY?}}/{{U8-READY?}} are thunks which are called when {{char-ready?}}120or {{u8-ready?}} are called on this port and should return {{#t}} or {{#f}}.121* {{CLOSE}} is a thunk which is called when the port is closed.122* {{peek-char}}/{{peek-u8}} are thunks which are called when {{peek-char}}123or {{peek-u8}} are124called on this port and should return a character/byte or {{#!eof}}. If125not provided or {{#f}}, {{READ-CHAR}}/{{READ-U8}} will be used instead and the126created port object handles peeking automatically (by calling the reader procedure127and buffering the character).128* {{read-bytevector}} is called when {{read-bytevector[!]}} or {{read-string[!]}} is called (or the129higher-level non-mutating {{read-string}} and {{read-bytevector}}). It will be invoked with 3130arguments: a bytevector to read into (which may be131assumed to be big enough to hold the data) and the offsets of the132starting and ending position into the133buffer at which to put the data to read. It should return the number134of bytes that have successfully been read, which should always be135equal to the requested bytes unless EOF was hit, in which case it can136be less. If this procedure is not provided or {{#f}}, the buffer will137be filled by repeated reads to {{READ-CHAR}}.138* {{READ-LINE}} is called when {{read-line}} is called. It will be139invoked with two arguments: the port created by {{make-input-port}}140and the maximum number of characters to read (or {{#f}}). If this141procedure is not provided or {{#f}}, the buffer will be filled by142repeated reads to {{READ-CHAR}}.143144All the optional procedures except for {{PEEK-CHAR}} are responsible145for updating the port's position, which currently can only be done via146low-level slot accessors like {{##sys#setslot}}; slot 4 is the row147number (ie, the line) and slot 5 is the column number (ie, the148character on the line). If the port's positions are not updated,149{{port-position}} won't work.150151Note that reading binary input from a custom non-binary input port is only possible152when the {{read-bytevector}} operation is given, as byte-input can153currently not ben synthesized from character-input operations.154155156==== make-output-port157==== make-binary-output-port158159<procedure>(make-output-port WRITE CLOSE #!key force-output)</procedure>160<procedure>(make-binary-output-port WRITE CLOSE #!key force-output write-bytevector)</procedure>161162Returns a custom output port. Common operations on this port are handled163by the given parameters, which should be procedures. {{WRITE}} is164called when output is sent to the port and receives a single argument,165a string for {{make-output-port}} or an integer for {{make-binary-output-port}}.166{{CLOSE}} is called when the port is closed and should167be a procedure of no arguments. {{force-output}} (if provided) is called168for flushing the output port. The optional {{write-bytevector}} allows169more optimized writing of partial buffers and takes 3 arguments: a170bytevector, a starting position and an ending position.171172173==== with-error-output-to-port174175<procedure>(with-error-output-to-port PORT THUNK)</procedure>176177Call procedure {{THUNK}} with the current error output-port178temporarily bound to {{PORT}}.179180181==== with-input-from-port182183<procedure>(with-input-from-port PORT THUNK)</procedure>184185Call procedure {{THUNK}} with the current input-port temporarily186bound to {{PORT}}.187188189=== String-port extensions190191==== call-with-input-string192193<procedure>(call-with-input-string STRING PROC)</procedure>194195Calls the procedure {{PROC}} with a single argument that is a196string-input-port with the contents of {{STRING}}.197198199==== call-with-output-string200201<procedure>(call-with-output-string PROC)</procedure>202203Calls the procedure {{PROC}} with a single argument that is a204string-output-port. Returns the accumulated output-string.205206207==== with-input-from-string208209<procedure>(with-input-from-string STRING THUNK)</procedure>210211Call procedure {{THUNK}} with the current input-port temporarily212bound to an input-string-port with the contents of {{STRING}}.213214215==== with-output-to-string216217<procedure>(with-output-to-string THUNK)</procedure>218219Call procedure {{THUNK}} with the current output-port temporarily220bound to a string-output-port and return the accumulated output string.221222==== with-error-output-to-string223224<procedure>(with-error-output-to-string THUNK)</procedure>225226Call procedure {{THUNK}} with the current error output-port227temporarily bound to a string-output-port and return the accumulated228output string.229230231=== Port iterators232233==== port-for-each234235<procedure>(port-for-each FN THUNK)</procedure>236237Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}} (typically {{read}}) until it returns {{#!eof}}, discarding the results.238239==== port-map240241<procedure>(port-map FN THUNK)</procedure>242243Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}} (typically {{read}}) until it returns {{#!eof}}, returning a list of the collected results.244245==== port-fold246247<procedure>(port-fold FN ACC THUNK)</procedure>248249Apply {{FN}} to successive results of calling the zero argument procedure {{THUNK}}, (typically {{read}}) passing the {{ACC}} value as the second argument. The {{FN}} result becomes the new {{ACC}} value. When {{THUNK}} returns {{#!eof}}, the last {{FN}} result is returned.250251==== copy-port252253<procedure>(copy-port FROM TO [READ [WRITE]])</procedure>254255Reads all remaining data from port {{FROM}} using the reader procedure256{{READ}} and writes it to port {{TO}} using the writer procedure257{{WRITE}}. {{READ}} defaults to {{read-char}} and {{WRITE}} to258{{write-char}}. Note that this procedure does not check {{FROM}} and259{{TO}} for being ports, so the reader and writer procedures may260perform arbitrary operations as long as they can be invoked261as {{(READ FROM)}} and {{(WRITE X TO)}}, respectively.262{{copy-port}} returns an undefined value.263264{{copy-port}} was introduced in CHICKEN 4.6.0.265266=== Funky ports267268==== make-bidirectional-port269270<procedure>(make-bidirectional-port INPUT-PORT OUTPUT-PORT)</procedure>271272Returns a joint input/output port that proxies port operations to the273given {{INPUT-PORT}} and {{OUTPUT-PORT}}, respectively. This port274satisfies both {{input-port?}} and {{output-port?}}, and its two275directions may be closed independently.276277==== make-broadcast-port278279<procedure>(make-broadcast-port PORT ...)</procedure>280281Returns a custom output port that emits everything written into it to282the ports given as {{PORT ...}}. Closing the broadcast port does not close283any of the argument ports.284285==== make-concatenated-port286287<procedure>(make-concatenated-port PORT1 PORT2 ...)</procedure>288289Returns a custom input port that reads its input from {{PORT1}}, until it290is empty, then from {{PORT2}} and so on. Closing the concatenated port291does not close any of the argument ports.292293294---295Previous: [[Module (chicken plist)]]296297Next: [[Module (chicken pretty-print)]]